docs: extend CONTRIBUTING.md with code guidelines by jlaportebot · Pull Request #4202 · google/go-github

jlaportebot · 2026-05-08T22:10:06Z

Summary

This PR extends CONTRIBUTING.md with a comprehensive section on code guidelines and conventions, addressing issue #4023.

Changes

Added a new "Code Guidelines" section that documents:

Naming Conventions
- File names ({service}_{api}.go pattern)
- Receiver names (consistently use 's')
- Request option types
- Request body types
- Response types
- Method and variable naming
- Common variable names (owner, repo, org, user, team, project)
- Enterprise and organization scoped methods
- Common structs (ListOptions, ListCursorOptions, UploadOptions, Response)
JSON Tags for Request Bodies
- Required fields: non-pointer types without omitempty
- Optional fields: pointer types with omitempty
- Use omitzero for structs and slices
URL Tags for Query Parameters
- All fields should be non-pointer types with url tags
- Use omitempty to omit zero values
Pagination
- Offset-based pagination (ListOptions)
- Cursor-based pagination (ListCursorOptions)
- Pagination best practices (embedding options, handling nil, using iterators)
Common Types
- ID fields: always int64
- Node ID fields: always string
- Timestamp fields: use Timestamp type
- Boolean fields: always *bool
Generation Patterns
- Generated accessors
- Generated iterators
- Generated documentation
- Linter rules (sliceofpointers, structfield)

Benefits

Helps new contributors understand the codebase better
Reduces review burden by making expectations explicit
Improves code consistency across the project
Documents patterns that are frequently discussed in reviews

Testing

This is a documentation-only change. No code changes or tests needed.

Closes #4023

Add comprehensive section documenting common code patterns and conventions: - Naming conventions (files, receivers, types, methods, variables) - JSON tags for request bodies (required vs optional fields, omitzero) - URL tags for query parameters (non-pointer fields with omitempty) - Pagination patterns (ListOptions, ListCursorOptions, best practices) - Common types (ID, NodeID, Timestamp, boolean fields) - Generation patterns (accessors, iterators, documentation, linter rules) This addresses issue google#4023 and helps new contributors understand the codebase better, reducing review burden and improving code consistency.

gmlewis

Thank you, @jlaportebot.
LGTM.

cc: @alexandear

codecov · 2026-05-08T22:22:26Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.71%. Comparing base (6c58592) to head (6fcb261).

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #4202   +/-   ##
=======================================
  Coverage   93.71%   93.71%           
=======================================
  Files         209      209           
  Lines       19772    19772           
=======================================
  Hits        18529    18529           
  Misses       1046     1046           
  Partials      197      197

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

alexandear

@jlaportebot Thank you. I left a few comments regarding excessive formatting and redundant information. Could you also review the entire CONTRIBUTING.md document and consolidate duplicated content?

Also, I think this PR should be reviewed by everyone listed in the REVIEWERS file.

alexandear · 2026-05-10T18:39:08Z


 [Go Doc Comments]: https://go.dev/doc/comment

+## Code Guidelines


I think the "Code Comments" section above should be under "Code Guidelines".

alexandear · 2026-05-10T18:41:29Z

+#### Generated Documentation
+
+Documentation links are automatically generated from `openapi_operations.yaml`.
+Run `script/generate.sh` to update these links.


These lines are not needed.

They are already in "Submitting a patch", "Metadata", and "Scripts".

Can be removed.

alexandear · 2026-05-10T18:42:12Z

+#### Linter Rules
+
+The repository uses custom linter rules to enforce consistency:
+- `sliceofpointers` - Ensures slice fields use pointers
+- `structfield` - Ensures struct fields follow naming conventions


We have more linters. Let's simply remove this section.

alexandear · 2026-05-10T18:43:30Z

+    State string `json:"state"`  // Required field
+    // ...


Please use TABs instead of spaces for all examples:

Suggested change

State string `json:"state"` // Required field

// ...

State string `json:"state"` // Required field

// ...

alexandear · 2026-05-10T18:46:24Z

+
+### Naming Conventions
+
+#### File Names


Should we remove the "Other notes on code organization" section?

alexandear · 2026-05-10T18:50:55Z

+#### Enterprise and Organization Scoped Methods
+
+Methods that operate on enterprise or organization resources include the scope
+in their name:
+
+```go
+// Enterprise-scoped methods
+func (s *EnterpriseService) GetLicenseInfo(ctx context.Context) (*LicenseInfo, *Response, error)
+
+// Organization-scoped methods
+func (s *OrganizationsService) ListMembers(ctx context.Context, org string, opts *OrganizationListMembersOptions) ([]*User, *Response, error)
+```


Actually, I think this subsection may be incorrect - see #3761.

alexandear · 2026-05-10T18:51:41Z

+
+When defining structs that represent a request body (sent via POST/PUT/PATCH):
+
+1. **Required fields** should be non-pointer types without `omitempty`:


Please do not use excessive LLM-like formatting:

Suggested change

1. **Required fields** should be non-pointer types without `omitempty`:

1. Required fields should be non-pointer types without `omitempty`:

alexandear · 2026-05-10T18:54:04Z

+2. **Handle nil options** in your methods:
+
+```go
+func (s *RepositoriesService) List(ctx context.Context, user string, opts *RepositoryListOptions) ([]*Repository, *Response, error) {
+    if opts == nil {
+        opts = &RepositoryListOptions{}
+    }
+    // ...
+}
+```


This can be removed. We have the addOptions to handle nil options.

gmlewis approved these changes May 8, 2026

View reviewed changes

alexandear suggested changes May 10, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: extend CONTRIBUTING.md with code guidelines#4202

docs: extend CONTRIBUTING.md with code guidelines#4202
jlaportebot wants to merge 1 commit intogoogle:masterfrom
jlaportebot:docs/extend-contributing-guidelines

jlaportebot commented May 8, 2026

Uh oh!

gmlewis left a comment

Uh oh!

codecov Bot commented May 8, 2026

Uh oh!

alexandear left a comment

Uh oh!

alexandear May 10, 2026

Uh oh!

alexandear May 10, 2026

Uh oh!

alexandear May 10, 2026

Uh oh!

alexandear May 10, 2026

Uh oh!

alexandear May 10, 2026

Uh oh!

alexandear May 10, 2026

Uh oh!

alexandear May 10, 2026

Uh oh!

alexandear May 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		[Go Doc Comments]: https://go.dev/doc/comment

		## Code Guidelines


		When defining structs that represent a request body (sent via POST/PUT/PATCH):

		1. Required fields should be non-pointer types without `omitempty`:

	1. Required fields should be non-pointer types without `omitempty`:
	1. Required fields should be non-pointer types without `omitempty`:

Conversation

jlaportebot commented May 8, 2026

Summary

Changes

Benefits

Testing

Uh oh!

gmlewis left a comment

Choose a reason for hiding this comment

Uh oh!

codecov Bot commented May 8, 2026

Codecov Report

Uh oh!

alexandear left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants